:Program.       Printf
:Author.        Volker Rudolph
:Address.       Lettow-Vorbeck-Str. 11 / 6750 Kaiserslautern 26
:Phone.         06301/8566
:Version.       1.2
:Date.          7.3.90
:Copyright.     PD
:Language.      Assembler / Oberon
:Translator.    A68k / Amiga-Oberon V1.17.1
:Contents.      Allzweck-Textausgabe in Form der C-Funktion Printf
:Usage.         Aufruf und Parameter wie in C

Oberon ist eine sehr gute Programmiersprache, sie hat aber auch einige
Schwächen. Am meisten hat mich die aufwendige Textausgabe gestört.
Allein ein einfacher Satz, wie 'Der Buchstabe A hat den ASCII-Code
65.', erfordert 6 Funktionsaufrufe.

char := 'A';
io.WriteString('Der Buchstabe ');
io.Write(char);
io.WriteString(' hat den ASCII-Code ');
io.WriteInt(ORD(char),2);
io.Write('.');
io.WriteLn;

In der Programmiersprache C ist das viel einfacher:
printf("Der Buchstabe %c hat den ASCII-Code %d.\n",char,char);

Deshalb habe ich das Modul Printf programmiert. Da es möglichst kurz
sein sollte, ist es komplett in Assembler geschrieben. Es enthält
Prozeduren, die den gleichen Aufruf und die gleiche Funktion haben,
wie das printf von C. Allerdings ist es in Oberon nicht wie in C
möglich, eine Funktion mit variabler Anzahl von Parametern zu
definieren. Deshalb gibt es 7 Funktionen: Printf0 bis Printf6. Die
Zahl hinter dem Printf entspricht der Anzahl der Parameter, die die
Funktion erwartet. Die Parameter sind alle von Typ LONGINT, da man die
meisten Variablen-Typen in LONGINT umwandeln kann.

Der Funktionsaufruf von Printf2 würde lauten:

Printf2("Der Buchstabe %lc hat den ASCII-Code %ld.\n", ORD(char),
ORD(char));

Die Format-Elemente (%s %ld etc.) haben das Format:

%[flags][breite.limit]typ

flags   : Es gibt nur das Flag '-'. Es bedeutet, daß das Argument in
          seinem Feld nach links ausgerichtet wird.
breite  : Minimale Feldbreite. Das Feld wird normalerweise mit Blanks
          aufgefüllt. Beginnt die Feldbreite mit einer 0, so wird mit
          '0' aufgefüllt.
limit   : Maximale Anzahl von Zeichen, die bei einem String ausgegeben
          werden.
typ     : ld : Dezimal
          lx : Hexadezimal
          lc : Zeichen
           s : String


Printf importiert kein weiteres Modul. Als Default werden die Texte
zur Standardausgabe (Dos.Ouput()) geschrieben. Falls man eine andere
Ausgabe bevorzugt, kann man aber der Prozedur-Variablen 'writeProc'
eine beliebige Prozedur vom Typ 'WriteProcType' zuweisen. Das ist zu
empfehlen, wenn das Programm auch von der Workbench aus gestartet
werden kann. Man sollte dann writeProc die Prozedur io.WriteString
zuweisen, da ohne io kein Ausgabefenster geöffnet wird. Der gesamte
Ausgabestring sollte nicht länger als 'bufSize' (120) Zeichen sein.
überzählige Zeichen werden abgeschnitten.

Einige Beispiele:

  p.Printf0("\[0;33;40m RED \[0;31;40m WHITE\n");
  RED wird in rot und WHITE in weiß ausgegeben (bei normaler Farbeinstellung)

  Die oben benutzte Kontroll-Sequenz hat das Format: "\[<style>;<fg>;<bg>m"
  Dabei lassen sich folgende Werte angeben:

    <style> =    0  plain text
                 1  bold-face
                 3  italic
                 4  underscore
                 7  inverse-video

    <fg>    =    30 - 37     Vordergrundfarbe 0 bis 7 (Standard : 0 bis 3)

    <bg>    =    40 - 47     Hintergrundfarbe 0 bis 7 (Standard : 0 bis 3)

  Man kann alle Kontroll-Sequenzen des Console.device benutzen.
  Siehe "Rom Kernel Reference Manual:Libraries and Devices"

  string := "Teststring";
  p.Printf2("Der String %6.8s ist %ld Zeichen lang.\n",
            sys.ADR(string),str.Length(string));
  >>Der String TestStri ist 10 Zeichen lang.
               12345678

  string := "Test";
  p.Printf2("Der String %6.8s ist %ld Zeichen lang.\n",
            sys.ADR(string),str.Length(string));
  >>Der String   Test ist 4 Zeichen lang.
               123456

  p.Printf2("Dezimal %3ld = Hex %04lx.\n",123H,123H);
  >>Dezimal 291 = Hex 0123.

Falls man einen String nicht direkt ausgeben will, sondern z.B. als
Parameter für einen Prozedur-Aufruf braucht, kann man anstelle von
Printfx die Prozeduren SPrintfx benutzen. Sie geben die Strings nicht
aus, sondern schreiben sie in einen Puffer, der mit übergeben wird.
Das ist auch praktisch, wenn der Ausgabestring länger als 120 Zeichen
ist.

Beispiel:
             .
             .
             .
IMPORT d:Dos,sys:SYSTEM,p:Printf;

VAR
  name:ARRAY 20 OF CHAR;
  buffer:ARRAY 80 OF CHAR;
  handle:d.FileHandlePtr;
BEGIN
  name := "Printf";
  p.SPrintf1(buffer,"DH0:Oberon/TXT/%s.mod",sys.ADR(name));
  handle := d.Open(buffer,d.newFile);
             .
             .
             .

  Das Programmstück öffnet die Datei "DH0:Oberon/TXT/Printf.mod"